Component brain instructions - #1
Merged
Merged
Conversation
Introduces MBT_COMPONENTS.md (V1) and templates/COMPONENTS_CLAUDE.md to support brains whose knowledge divides into several components, each with its own namespace, directory, and work-item log. Updates MBT_PATTERN.md, MBT_CREATE_BRAIN.md, MBT_CHECK_BRAIN.md, CLAUDE.md, and all affected templates to reflect the layer; fixes namespace-token gaps and the session-closeout fallback for multi-log brains.
An adversarial pass over MBT_COMPONENTS, MBT_CREATE_BRAIN, and every template a component brain instantiates, using the virtual-view-brain bootstrap plan as the reference case and both exemplar brains as compatibility checks. Establishes the two-tier placeholder contract — <PREFIX> is the brain/hub token resolved at creation, <TOKEN> the owning unit's token resolved at runtime — across the session-closeout, work-setup/closeout, and work scaffolds, whose patterns previously corrupted under substitution in component brains. Pins the routing ambiguities: sessions log to the nearest common ancestor of the units their work concerned (not merely read), a work item's merged log entries all land in its owner's canonical log, and questions no component claims are hub-level. Adds the longest-prefix naming constraint (a parent's name must not extend into a child's token) with guardrails where names get chosen, corrects the restructuring rows (a fresh hub token with maintenance-doc renames; migrated platform units author their missing SCOPE/APPROACH; children are seeded and parents cede content), restores dropped rules to the component entrypoint template (never a bare CLAUDE.md, logs never archived, move-not-delete retirement, maturity blocks), sanctions log-appending procedures citing the session-closeout format authority, renames the work-item "prefix" to slug, and makes instantiated brains self-contained by inlining the six work scaffolds. The toolkit's own dream cycle now sweeps the spec-template pair for drift. The point-in-time review is archived as MBT_COMPOUND_FABLE_REVIEW; the remaining open items — the component dream cycle, work-item re-homing, registry maintenance, and the two migration holes — stand as working/MBT_COMPOUND_RESEARCH with per-area confidence scores.
…ffolded work items
…he dream-cycle template
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
MBT_COMPONENTS.mdandtemplates/COMPONENTS_CLAUDE.md— an opt-in convention for brains whose knowledge divides into several components, each with its own namespace, directory, and work-item logMBT_CREATE_BRAIN.md's authoring rules, andMBT_CHECK_BRAIN.md's drift check (MBT_SCOPE.mditself is unchanged)MBT_PATTERN.md,MBT_DREAM_CYCLE.md,CLAUDE.md, and all affected templatesTest plan
MBT_CREATE_BRAIN.mdand verify no regressionsMBT_CHECK_BRAIN.mdagainst both brain typesRun on 2026-08-08 against fixture brains seeded from the templates literally — a single-unit brain and a three-level component brain covering nested tokens, a non-nested token, and a sub-component. Both seeds executed with no improvisation: two-tier placeholder contract, per-unit substitution, registry fill, and README reword all behaved as written, and the check procedure passed on both. A deliberately misplaced document (a child-token file at the hub root) was caught by the new anchored namespace check. The one defect the run surfaced was pre-existing and is fixed here (
a87c3fd). Every runnable check command was also executed against fixtures including its failure cases, which is what caught the three that failed open under zsh.Follow-ups
Three work items land as dormant scaffolds in
working/, each gated on a living multi-component brain rather than designed on paper. They ship separately when their triggers fire:MIGRATIONS— an extraction kit for a component leaving as its own brainREHOMING— a move procedure for a work item that outgrows its owning unitCOMPONENT_DREAM— a component-aware dream cycle, and the cycle as the component registry's assigned maintainer. Until it lands,MBT_CREATE_BRAIN.mdwarns against instantiating the dream-cycle template unadapted into a component brain